Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion agent_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -1471,6 +1471,13 @@ 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])
Expand Down Expand Up @@ -1974,6 +1981,12 @@ 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.

Expand Down Expand Up @@ -2382,6 +2395,8 @@ def _private_file(path, maximum):

class AgentClient:
"""No catalog access, automatic retries, redirects, proxies or owner identity."""
MAX_TIMEOUT_SECONDS = 300

def __init__(self, endpoint, token, expected_catalog_id, timeout=120):
try:
parsed = urlsplit(endpoint)
Expand All @@ -2391,7 +2406,7 @@ def __init__(self, endpoint, token, expected_catalog_id, timeout=120):
raise ValueError()
if not re.fullmatch(r'[A-Za-z0-9_-]{20,4096}', token) or not re.fullmatch('[a-f0-9]{32}', expected_catalog_id):
raise ValueError()
if type(timeout) not in (int, float) or not math.isfinite(timeout) or not 0 < timeout <= 300:
if type(timeout) not in (int, float) or not math.isfinite(timeout) or not 0 < timeout <= self.MAX_TIMEOUT_SECONDS:
raise ValueError()
except (ValueError, TypeError):
raise AgentAPIError('Invalid fixed loopback client configuration.', 'configuration') from None
Expand Down Expand Up @@ -3016,6 +3031,10 @@ def call(self, name, arguments, *, observer=None, observation=None):

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

Expand Down
1 change: 1 addition & 0 deletions app.py
Original file line number Diff line number Diff line change
Expand Up @@ -919,6 +919,7 @@ def _get(self):
'/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'),
Expand Down
10 changes: 10 additions & 0 deletions docs/contracts/project-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,16 @@ annotations; human review still requires the owner. Every project action is boun
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
Expand Down
87 changes: 87 additions & 0 deletions docs/contracts/project-model-portfolio.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# 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.
17 changes: 16 additions & 1 deletion project_composition.py
Original file line number Diff line number Diff line change
Expand Up @@ -268,8 +268,23 @@ def allocate(family,identity,revision):
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=artifact_plan(records))
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,
Expand Down
4 changes: 2 additions & 2 deletions project_custody.py
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ def _directory(self, create=False):
finally:os.close(parent)

def _binding(self, store, projection_id):
snapshot=store.snapshot()
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'],
Expand Down Expand Up @@ -247,7 +247,7 @@ def __init__(self, owner, store, binding):
persisted=value is not None
if value is None:
value=dict(format='project_local_custody_v1',**binding,
project_name=store.snapshot()['name'],selected_checkpoint=store.snapshot()['checkpoint'],
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)
Expand Down
10 changes: 5 additions & 5 deletions project_data.py
Original file line number Diff line number Diff line change
Expand Up @@ -1001,7 +1001,7 @@ def _publish(self, raw, kind, role, media_type):
declaration = dict(format='project_artifact_v1', sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw))
self.artifacts.publish_bytes(raw, declaration)
self._pending_artifacts[declaration['sha256']] = declaration
return dict(artifact=dict(namespace=self.session.snapshot['project_id'], sha256=declaration['sha256']),
return dict(artifact=dict(namespace=self.session.summary['project_id'], sha256=declaration['sha256']),
media_type=media_type, kind=kind, role=role, preservation='unique', required_for=['inspect', 'release'])

def _require_record(self, record_id, *, extended=False):
Expand All @@ -1028,7 +1028,7 @@ def _mutate(self, operation, target, body, expected_checkpoint, key, invoke):
fail('Data mutation body must be an object.')
self._permission(operation, target, body)
with self.session.lock, self.db.lock:
self.session.check()
self.session.check_current()
if operation in ('data.annotate','data.correct_rights_note','data.save_image_source','data.delete_image_source'):
self._require_record(target,extended=operation!='data.annotate')
legacy = self._legacy_replay(operation, target, body, key)
Expand Down Expand Up @@ -1158,10 +1158,10 @@ def freeze_release(self, body, expected_checkpoint, key):
def _read(self, action, invoke, target=None):
with self.access.lock, self.session.lock, self.db.lock:
self.access.require('inspect', action, target)
self.session.check()
self.session.check_current()
self._sync_sources()
result = invoke()
self.session.check()
self.session.check_current()
return result

def query(self, options=None):
Expand Down Expand Up @@ -1399,7 +1399,7 @@ def restore(self, snapshot=None):
self.db.execute('INSERT INTO saved_searches VALUES (%s,%s,%s,%s,%s,%s)', (record_id,r['name'],r['revision'],encode_retained(r['criteria']),r['created_at'],r['updated_at']))
elif family == 'dataset_exposure':
self.db.execute('INSERT INTO workspace_exposures VALUES (%s,%s,%s,%s,%s,%s,%s)', tuple(doc[k] for k in ('id','record_id','source_hash','reason','run_id','release_id','created_at')))
self.session.check()
self.session.check_current()
self._materialize_images_and_releases(owned)
return snapshot

Expand Down
20 changes: 11 additions & 9 deletions project_dispatch.py
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ def _data(projection, action, a):
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.snapshot['project_id']]
if kind == family and doc['origin_catalog_id'] == projection.session.summary['project_id']]
return _page(sorted(values, key=lambda item: item['id']), a)


Expand Down Expand Up @@ -370,7 +370,16 @@ def _m4(projection,action,a):
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);snapshot=session.check()
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':
Expand All @@ -390,13 +399,6 @@ def _m4(projection,action,a):
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)
if action=='fork_info':
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)
raise AssertionError('Closed M4 dispatch is incomplete.')


Expand Down
Loading
Loading