sg-python-api 0.2.0__tar.gz → 0.2.1__tar.gz

{sg_python_api-0.2.0 → sg_python_api-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sg-python-api
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python client for Autodesk Flow Production Tracking
 Project-URL: Documentation, https://github.com/dactylo/sg-python-api/tree/main/docs
 Project-URL: Homepage, https://github.com/dactylo/sg-python-api
@@ -45,8 +45,8 @@ This documentation uses SG for Flow Production Tracking, formerly named Shotgun
 
 sg-python-api is an independent implementation of the documented API of Autodesk's Python client
 `3.10.5`. Some behavior differs on purpose, so validate your application's workflows against a test
-site before replacing its production client. The [migration guide](https://github.com/dactylo/sg-python-api/blob/v0.2.0/docs/migration-guide.md) walks
-through the switch, and the [compatibility reference](https://github.com/dactylo/sg-python-api/blob/v0.2.0/COMPATIBILITY.md) lists the differences.
+site before replacing its production client. The [migration guide](https://github.com/dactylo/sg-python-api/blob/v0.2.1/docs/migration-guide.md) walks
+through the switch, and the [compatibility reference](https://github.com/dactylo/sg-python-api/blob/v0.2.1/COMPATIBILITY.md) lists the differences.
 
 ## Installation
 
@@ -55,7 +55,7 @@ requests to a remote site require HTTPS.
 
 `sg-python-api` and Autodesk's `shotgun-api3` both install the `shotgun_api3` package, so install
 exactly one of them in a Python environment. If the official client is already installed, follow
-the [migration steps](https://github.com/dactylo/sg-python-api/blob/v0.2.0/docs/migration-guide.md#install-the-replacement) to replace it.
+the [migration steps](https://github.com/dactylo/sg-python-api/blob/v0.2.1/docs/migration-guide.md#install-the-replacement) to replace it.
 
 From a checkout, install into the Python environment that runs your application:
 
@@ -127,23 +127,23 @@ asyncio.run(main())
 
 The output matches the synchronous example. The `async with` block closes the client even when an
 operation fails. Share an `AsyncShotgun` only among tasks on one event loop. See the
-[async reference](https://github.com/dactylo/sg-python-api/blob/v0.2.0/COMPATIBILITY.md#async-extension-surfaces) for lifecycle and cancellation
+[async reference](https://github.com/dactylo/sg-python-api/blob/v0.2.1/COMPATIBILITY.md#async-extension-surfaces) for lifecycle and cancellation
 details.
 
 ## Documentation
 
 | If you want to...                                                  | Read                                                                               |
 | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
-| Replace Autodesk's client in an existing application               | [Migration guide](https://github.com/dactylo/sg-python-api/blob/v0.2.0/docs/migration-guide.md)                                         |
-| Check what behaves differently from Autodesk's client              | [Compatibility](https://github.com/dactylo/sg-python-api/blob/v0.2.0/COMPATIBILITY.md)                                                  |
-| Tune pooling, TCP keepalive, or page prefetch, or observe requests | [Configuration extensions](https://github.com/dactylo/sg-python-api/blob/v0.2.0/COMPATIBILITY.md#configuration-and-observer-extensions) |
-| Confirm which client loads and run a smoke test                    | [Testing an installation](https://github.com/dactylo/sg-python-api/blob/v0.2.0/docs/testing.md)                                         |
-| Compare measured latency and transfer memory                       | [Benchmarks](https://github.com/dactylo/sg-python-api/blob/v0.2.0/docs/benchmarks.md)                                                   |
-| See changes by version                                             | [Changelog](https://github.com/dactylo/sg-python-api/blob/v0.2.0/CHANGELOG.md)                                                          |
+| Replace Autodesk's client in an existing application               | [Migration guide](https://github.com/dactylo/sg-python-api/blob/v0.2.1/docs/migration-guide.md)                                         |
+| Check what behaves differently from Autodesk's client              | [Compatibility](https://github.com/dactylo/sg-python-api/blob/v0.2.1/COMPATIBILITY.md)                                                  |
+| Tune pooling, TCP keepalive, or page prefetch, or observe requests | [Configuration extensions](https://github.com/dactylo/sg-python-api/blob/v0.2.1/COMPATIBILITY.md#configuration-and-observer-extensions) |
+| Confirm which client loads and run a smoke test                    | [Testing an installation](https://github.com/dactylo/sg-python-api/blob/v0.2.1/docs/testing.md)                                         |
+| Compare measured latency and transfer memory                       | [Benchmarks](https://github.com/dactylo/sg-python-api/blob/v0.2.1/docs/benchmarks.md)                                                   |
+| See changes by version                                             | [Changelog](https://github.com/dactylo/sg-python-api/blob/v0.2.1/CHANGELOG.md)                                                          |
 
 ## Development
 
-See the [development guide](https://github.com/dactylo/sg-python-api/blob/v0.2.0/docs/development.md) for the required tools, CI, and dependency locks.
+See the [development guide](https://github.com/dactylo/sg-python-api/blob/v0.2.1/docs/development.md) for the required tools, CI, and dependency locks.
 With those tools installed, run:
 
 ```sh
@@ -151,11 +151,11 @@ make setup
 make check TEST_FLAGS="-m 'not live'"
 ```
 
-See [live-site tests](https://github.com/dactylo/sg-python-api/blob/v0.2.0/docs/development.md#live-site-tests) to configure tests that create and
+See [live-site tests](https://github.com/dactylo/sg-python-api/blob/v0.2.1/docs/development.md#live-site-tests) to configure tests that create and
 retire records on a disposable site.
 
 ## License
 
-sg-python-api is available under the [MIT License](https://github.com/dactylo/sg-python-api/blob/v0.2.0/LICENSE). It is an independent project and is
+sg-python-api is available under the [MIT License](https://github.com/dactylo/sg-python-api/blob/v0.2.1/LICENSE). It is an independent project and is
 not affiliated with or endorsed by Autodesk. Flow Production Tracking is a product of Autodesk,
 Inc.

{sg_python_api-0.2.0 → sg_python_api-0.2.1}/pyproject.toml

@@ -10,7 +10,7 @@ requires = [ "editables~=0.3", "hatch-fancy-pypi-readme>=25.1", "hatchling>=1.27
 # ==========================================================
 [project]
 name = "sg-python-api"
-version = "0.2.0"
+version = "0.2.1"
 description = "Python client for Autodesk Flow Production Tracking"
 keywords = [ "api", "flow-production-tracking", "shotgrid", "shotgun", "shotgun-api3" ]
 license = "MIT"

{sg_python_api-0.2.0 → sg_python_api-0.2.1}/src/shotgun_api3/lib/mockgun/_events.py

@@ -111,6 +111,9 @@ _LIFECYCLE_TYPES = frozenset(
         'Asset',
         'PublishedFile',
         'CutItem',
+        # 2026-11-10: a lone Cut or Attachment logs only its own lifecycle rows.
+        'Cut',
+        'Attachment',
     }
 )
 _LINK_TARGETS = {
@@ -145,6 +148,10 @@ _LINK_UPDATE_FORMS = {
 _SCALAR_ENCODINGS = frozenset(
     {'number', 'duration', 'checkbox', 'text', 'list', 'status_list', 'date', 'date_time', 'float'}
 )
+# 2026-11-10 trial capture: no create logs a default it fills into a field of these data types,
+# across 459 Task, 240 Note, 83 Reply and 36 Playlist creates; status list and list defaults are
+# always logged.
+_UNLOGGED_DEFAULT_TYPES = frozenset({'duration', 'number', 'percent', 'text'})
 _WRITE_TYPES = frozenset(
     {
         'Shot',
@@ -216,6 +223,10 @@ def _create_fields(store: Store, row: Row, supplied: Sequence[str]) -> list[str]
         if field not in _CREATE_IGNORED
         and row.get(field) is not None
         and row.get(field) != []
+        and not (
+            field not in supplied
+            and store.schema.field_type(kind, field) in _UNLOGGED_DEFAULT_TYPES
+        )
         and not (
             field not in supplied
             and row.get(field) is False
@@ -718,7 +729,13 @@ def _observed_create_fields(
     populated = {
         field
         for field in store.schema.fields[kind]
-        if field not in _CREATE_IGNORED and row.get(field) is not None and row.get(field) != []
+        if field not in _CREATE_IGNORED
+        and row.get(field) is not None
+        and row.get(field) != []
+        and not (
+            field not in supplied
+            and store.schema.field_type(kind, field) in _UNLOGGED_DEFAULT_TYPES
+        )
     }
     for form in _CREATE_FORMS:
         if (kind, session) != (form.kind, form.session):
@@ -862,10 +879,14 @@ def record_create(
     plans = _plan_create(store, row, supplied, context=context)
     if store.schema.declares('EventLogEntry') and store.events_unknown is None:
         if plans is None:
-            _unsettled(
-                store,
-                f'{row["type"]} {row["id"]} create has unsettled event rows',
+            # 2026-11-10: a new Project also logs hundreds of rows for the pages,
+            # page settings and field preferences the site copies from a template.
+            detail = (
+                ' for the pages and preferences the site creates with it'
+                if row['type'] == 'Project'
+                else ''
             )
+            _unsettled(store, f'{row["type"]} {row["id"]} create has unsettled event rows{detail}')
         else:
             _write_plans(store, plans, context)
     return plans is not None

{sg_python_api-0.2.0 → sg_python_api-0.2.1}/src/shotgun_api3/lib/mockgun/_handlers.py

@@ -27,7 +27,6 @@ from ._wire import RpcCall
 
 if TYPE_CHECKING:
     from ._server import FakeServer
-    from ._store import FieldValue
 
 _Handler: TypeAlias = Callable[['FakeServer', RpcCall, RequestContext], object]
 HANDLERS: dict[str, _Handler] = {}
@@ -385,6 +384,7 @@ def _update(server: 'FakeServer', call: RpcCall, context: RequestContext) -> obj
     entity_type = cast('str', params['type'])
     entity_id = cast('int', params['id'])
     _check_event_write(server, entity_type)
+    server.store.check_link_targets(entity_type, fields, 'update')
     kept = kept_members(server.store, entity_type, entity_id, fields)
     effective = server.store.kept_fields(
         server.store.require(entity_type, entity_id), fields, modes, kept
@@ -401,11 +401,6 @@ def _update(server: 'FakeServer', call: RpcCall, context: RequestContext) -> obj
         row = server.store.update(
             entity_type, entity_id, effective, effective_modes, context=context
         )
-        for field in kept:
-            if len(cast('list[FieldValue]', row[field])) > 1:
-                server.store.mark_unknown(
-                    row, field, 'retained hidden members have unsettled order', order_only=True
-                )
         settled = record_update(
             server.store,
             before,

{sg_python_api-0.2.0 → sg_python_api-0.2.1}/src/shotgun_api3/lib/mockgun/_links.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 from typing import cast
 
 from ._errors import MockgunError
-from ._store import FieldValue, Row, Store
+from ._store import CONNECTION_FIELDS, FieldValue, Row, Store
 
 
 @dataclass(frozen=True)
@@ -43,19 +43,28 @@ _DISPLAY_FIELDS = {
     'ApiUser': ('firstname', 'lastname'),
 }
 _DISPLAY_LIMIT = 255
+# Fields the site keeps in NoteLink and NoteTask records, which mockgun does not
+# store; a retired holder hides their members (2026-11-10 live comparison).
+_IMPLICIT_CONNECTIONS = {
+    'Note': frozenset({'note_links', 'tasks'}),
+    'Shot': frozenset({'notes'}),
+}
 _RETIREMENT_EDGES = {
+    # 2026-11-10: Attachment and Note links hide; neither end is touched or logged.
     ('Attachment', 'attachment_links', 'Note'): _RetirementRule(
-        'keep', 'always', touched=False, settled=False
+        'hide', 'always', touched=False, settled=True
     ),
     ('Attachment', 'attachment_links', 'Version'): _RetirementRule(
-        'keep', 'always', touched=False, settled=False
+        'hide', 'always', touched=False, settled=True
     ),
     ('Note', 'attachments', 'Attachment'): _RetirementRule(
-        'keep', 'always', touched=False, settled=False
+        'hide', 'always', touched=False, settled=True
     ),
-    ('Task', 'entity', 'Shot'): _RetirementRule('cascade', 'always', touched=False, settled=False),
+    # 2026-11-10: a live Task whose Shot is revived gains no event rows.
+    ('Task', 'entity', 'Shot'): _RetirementRule('cascade', 'always', touched=False, settled=True),
+    # 2026-11-10: a live Version whose Shot is revived gains no event rows.
     ('Version', 'entity', 'Shot'): _RetirementRule(
-        'cascade', 'always', touched=False, settled=False
+        'cascade', 'always', touched=False, settled=True
     ),
     ('Task', 'entity', 'Asset'): _RetirementRule(
         'cascade', 'always', touched=False, settled=False
@@ -108,8 +117,13 @@ _RETIREMENT_EDGES = {
     ),
     ('CutItem', 'shot', 'Shot'): _RetirementRule('hide', 'always', touched=False, settled=True),
     ('PublishedFile', 'entity', 'Asset'): _RetirementRule(
-        'hide', 'always', touched=False, settled=False
+        'hide', 'always', touched=False, settled=True
     ),
+    ('PublishedFile', 'entity', 'Sequence'): _RetirementRule(
+        'hide', 'always', touched=False, settled=True
+    ),
+    ('TimeLog', 'entity', 'Shot'): _RetirementRule('hide', 'always', touched=False, settled=True),
+    ('TimeLog', 'entity', 'Task'): _RetirementRule('hide', 'always', touched=False, settled=True),
     ('Shot', 'sg_sequence', 'Sequence'): _RetirementRule(
         'hide', 'always', touched=False, settled=True
     ),
@@ -122,10 +136,11 @@ _RETIREMENT_EDGES = {
     ),
     ('Version', 'sg_task', 'Task'): _RetirementRule('hide', 'always', touched=False, settled=True),
     ('PublishedFile', 'task', 'Task'): _RetirementRule(
-        'hide', 'always', touched=False, settled=False
+        'hide', 'always', touched=False, settled=True
     ),
     ('Sequence', 'shots', 'Shot'): _RetirementRule('hide', 'always', touched=False, settled=False),
-    ('Shot', 'tasks', 'Task'): _RetirementRule('hide', 'always', touched=False, settled=False),
+    # 2026-11-10: retiring or reviving a Task alone adds no row for its Shot.
+    ('Shot', 'tasks', 'Task'): _RetirementRule('hide', 'always', touched=False, settled=True),
     ('Shot', 'notes', 'Note'): _RetirementRule('hide', 'always', touched=False, settled=False),
     ('Version', 'published_files', 'PublishedFile'): _RetirementRule(
         'hide', 'always', touched=False, settled=False
@@ -143,7 +158,27 @@ _RETIREMENT_EDGES = {
     ('Asset', 'assets', 'Asset'): _RetirementRule('hide', 'always', touched=True, settled=False),
     ('Shot', 'assets', 'Asset'): _RetirementRule('hide', 'always', touched=True, settled=False),
     ('Asset', 'shots', 'Shot'): _RetirementRule('hide', 'always', touched=True, settled=False),
-    ('CutItem', 'cut', 'Cut'): _RetirementRule('keep', 'always', touched=False, settled=False),
+    # 2026-11-10: a CutItem outlives its Cut with the link hidden and no rows.
+    ('CutItem', 'cut', 'Cut'): _RetirementRule('hide', 'always', touched=False, settled=True),
+    # 2026-11-10: a connection record retires with either end and revives with it.
+    ('AssetShotConnection', 'shot', 'Shot'): _RetirementRule(
+        'cascade', 'always', touched=False, settled=False
+    ),
+    ('AssetShotConnection', 'asset', 'Asset'): _RetirementRule(
+        'cascade', 'always', touched=False, settled=False
+    ),
+    ('AssetAssetConnection', 'parent', 'Asset'): _RetirementRule(
+        'cascade', 'always', touched=False, settled=False
+    ),
+    ('AssetAssetConnection', 'asset', 'Asset'): _RetirementRule(
+        'cascade', 'always', touched=False, settled=False
+    ),
+    ('PlaylistVersionConnection', 'version', 'Version'): _RetirementRule(
+        'cascade', 'always', touched=False, settled=False
+    ),
+    ('PlaylistVersionConnection', 'playlist', 'Playlist'): _RetirementRule(
+        'cascade', 'always', touched=False, settled=False
+    ),
 }
 _NOTE_COMBINED_LIMIT = 83
 _NOTE_SUBJECT_LIMIT = 120
@@ -154,8 +189,8 @@ class RetirementEdge:
     """Describe an immutable link retirement effect and its completeness.
 
     Attributes:
-        effect: `hide`, `keep`, `cascade`, or `taint`, describing the effect on
-            the holder when the target is retired.
+        effect: `hide`, `cascade`, or `taint`, describing the effect on the
+            holder when the target is retired.
         touched: Whether hiding the link affects the holder's update audit
             fields.
         settled: Whether the edge's lifecycle-event effects are fully modeled.
@@ -195,26 +230,23 @@ def _listed(holder: Row, field_name: str, link: Mapping[str, FieldValue]) -> boo
     )
 
 
-def _note_edge(store: Store, holder: Row, target: Row) -> RetirementEdge:
-    """Resolve the two observed Note.note_links shapes."""
-    links = cast('list[dict[str, FieldValue]]', holder.get('note_links', []))
-    if holder.get('tasks'):
-        return RetirementEdge('taint')
-    if len(links) == 1:
-        return RetirementEdge('cascade')
-    others = [
-        link for link in links if (link['type'], link['id']) != (target['type'], target['id'])
-    ]
-    if (
-        len(others) == 1
-        and len(links) == len(others) + 1
-        and target['type'] == 'Shot'
-        and others[0]['type'] == 'Asset'
-    ):
-        other = store.row('Asset', cast('int', others[0]['id']))
-        if other is not None and not other['__retired'] and not store.tainted(other):
-            return RetirementEdge('hide')
-    return RetirementEdge('taint')
+def _retired_target(target: Row, assume: Mapping[tuple[str, int], RecordState] | None) -> bool:
+    """Return a target's assumed or settled retirement, rejecting an unsettled one."""
+    state = (
+        assume.get((cast('str', target['type']), cast('int', target['id']))) if assume else None
+    )
+    if state is not None:
+        return state.retired
+    taint = cast('dict[str, FieldValue]', target.get('__taint', {}))
+    if taint and not taint.get('active'):
+        raise MockgunError(f'{target["type"]} {target["id"]}: {taint["reason"]}')
+    return bool(target['__retired'])
+
+
+def _uncertain(row: Row) -> bool:
+    """Return whether a record's own retirement state is unsettled."""
+    taint = cast('dict[str, FieldValue]', row.get('__taint', {}))
+    return bool(taint) and not taint.get('active')
 
 
 def _unsettled(entity_type: str, fields: tuple[str, ...]) -> MockgunError:
@@ -293,6 +325,45 @@ def _display(store: Store, entity_type: str, entity_id: int) -> tuple[str | None
     return name, derived
 
 
+def connection_backed(holder: Row, field_name: str, target: Row) -> bool:
+    """Return whether the site keeps a link's membership in a connection record.
+
+    A retired holder hides such a member while its connection record is
+    retired, even when the target is active.
+    """
+    kind = cast('str', holder['type'])
+    return (kind, field_name, cast('str', target['type'])) in CONNECTION_FIELDS or (
+        field_name in _IMPLICIT_CONNECTIONS.get(kind, frozenset())
+    )
+
+
+def connection_record(store: Store, holder: Row, field_name: str, target: Row) -> Row | None:
+    """Return the stored connection record behind one member, retired or not.
+
+    Returns:
+        The live stored connection row, or `None` when the schema declares no
+        such record or none joins the two records.
+    """
+    definition = CONNECTION_FIELDS.get(
+        (cast('str', holder['type']), field_name, cast('str', target['type']))
+    )
+    if definition is None:
+        return None
+    connection_type, holder_side, target_side = definition
+    if not (
+        store.schema.declares(connection_type, holder_side)
+        and store.schema.declares(connection_type, target_side)
+    ):
+        return None
+    return store.connection_row(
+        connection_type,
+        {
+            holder_side: {'type': holder['type'], 'id': holder['id']},
+            target_side: {'type': target['type'], 'id': target['id']},
+        },
+    )
+
+
 def derived_name(store: Store, entity_type: str, entity_id: int) -> bool:
     """Return whether a modeled name uses Task fallback or Note truncation.
 
@@ -311,37 +382,99 @@ def display_name(store: Store, entity_type: str, entity_id: int) -> str | None:
     return _display(store, entity_type, entity_id)[0]
 
 
-def named_link(store: Store, link: Mapping[str, FieldValue]) -> dict[str, FieldValue]:
-    """Return a detached identity with a name when the target is modeled.
+def implicit_connection_fields(entity_type: str) -> frozenset[str]:
+    """Return a type's connection-backed fields whose records mockgun does not store."""
+    return _IMPLICIT_CONNECTIONS.get(entity_type, frozenset())
 
-    Raises:
-        MockgunError: If the target's display name is unsettled.
+
+def implicit_link_hidden(holder: Row, field_name: str, target: Row) -> bool:
+    """Return whether a retired holder hides an active NoteLink or NoteTask member.
+
+    The internal record stays retired with the holder, unless the target
+    retired first and so revived it on its own revival (2026-11-10).
     """
-    result = {'type': link['type'], 'id': link['id']}
-    name = display_name(store, cast('str', link['type']), cast('int', link['id']))
-    if name is not None:
-        result['name'] = name
-    return result
+    member: FieldValue = [field_name, target['type'], target['id']]
+    return member not in cast('list[FieldValue]', holder.get('__retired_hidden', []))
 
 
-def retirement_edge(store: Store, holder: Row, field_name: str, target: Row) -> RetirementEdge:
-    """Resolve a retirement edge, including its observed holder conditions."""
-    kind = cast('str', holder['type'])
-    target_type = cast('str', target['type'])
-    if kind == 'EventLogEntry' and field_name == 'entity':
-        return RetirementEdge('hide')
-    rule = _RETIREMENT_EDGES.get((kind, field_name, target_type))
-    if rule is None or (target_type == 'Project' and target.get('archived')):
-        return RetirementEdge('taint')
-    if rule.condition == 'note_links':
-        return _note_edge(store, holder, target)
-    if rule.condition == 'tasks' and (
-        holder.get('note_links') or len(cast('list[FieldValue]', holder.get('tasks', []))) != 1
+def _retired_holder_hidden(
+    store: Store,
+    holder: Row,
+    field_name: str,
+    target: Row,
+    assume: Mapping[tuple[str, int], RecordState] | None,
+) -> bool:
+    """Resolve a retired holder's link from its target and any connection record."""
+    if _retired_target(target, assume):
+        return True
+    if not connection_backed(holder, field_name, target):
+        return False
+    record = connection_record(store, holder, field_name, target)
+    if record is not None:
+        return _retired_target(record, assume)
+    return implicit_link_hidden(holder, field_name, target)
+
+
+def link_target(store: Store, link: Mapping[str, FieldValue]) -> Row | None:
+    """Return the stored record a link names, including a retired one.
+
+    Returns:
+        The live stored row, or `None` when the link is malformed, names an
+        undeclared entity type, or names a missing record.
+    """
+    kind, identity = link.get('type'), link.get('id')
+    if (
+        not isinstance(kind, str)
+        or not isinstance(identity, int)
+        or not store.schema.declares(kind)
     ):
+        return None
+    return store.row(kind, identity)
+
+
+def _live(store: Store, link: Mapping[str, FieldValue]) -> bool:
+    """Return whether a link names an existing active record with settled state."""
+    row = link_target(store, link)
+    return row is not None and not row['__retired'] and not store.tainted(row)
+
+
+def _chained_task(store: Store, holder: Row, target: Row) -> bool:
+    """Identify a Note linked to a Shot and to one live Task of that Shot."""
+    links = cast('list[dict[str, FieldValue]]', holder.get('note_links', []))
+    tasks = cast('list[dict[str, FieldValue]]', holder.get('tasks', []))
+    identity = {'type': target['type'], 'id': target['id']}
+    if target['type'] != 'Shot' or len(tasks) != 1 or links != [identity]:
+        return False
+    task = link_target(store, tasks[0])
+    return task is not None and task.get('entity') == identity and _live(store, tasks[0])
+
+
+def _note_edge(store: Store, holder: Row, target: Row) -> RetirementEdge:
+    """Resolve the observed Note.note_links shapes, including the Shot-Task chain."""
+    links = cast('list[dict[str, FieldValue]]', holder.get('note_links', []))
+    if holder.get('tasks'):
+        # A Note created for a Task also links the Task's Shot; both retire with the Shot.
+        return RetirementEdge('cascade' if _chained_task(store, holder, target) else 'taint')
+    if len(links) == 1:
+        return RetirementEdge('cascade')
+    others = [
+        link for link in links if (link['type'], link['id']) != (target['type'], target['id'])
+    ]
+    # 2026-11-10: a two-link Note survives either link's retirement while the other is live.
+    if len(others) == 1 and len(links) == len(others) + 1 and _live(store, others[0]):
+        return RetirementEdge('hide')
+    return RetirementEdge('taint')
+
+
+def _task_note_edge(store: Store, holder: Row, rule: _RetirementRule) -> RetirementEdge:
+    """Resolve a Note's single Task link by whether a live note_links target remains."""
+    links = cast('list[dict[str, FieldValue]]', holder.get('note_links', []))
+    if len(cast('list[FieldValue]', holder.get('tasks', []))) != 1:
         return RetirementEdge('taint')
-    if rule.condition == 'note_project' and (holder.get('note_links') or holder.get('tasks')):
-        return RetirementEdge('taint')
-    return RetirementEdge(rule.effect, rule.touched, rule.settled)
+    if not links:
+        return RetirementEdge(rule.effect, rule.touched, rule.settled)
+    # 2026-11-10: a Note keeping a live note_links target survives its Task.
+    return RetirementEdge('hide' if all(_live(store, link) for link in links) else 'taint')
 
 
 def deciding_record(
@@ -356,29 +489,21 @@ def deciding_record(
         link: Target identity with `type` and `id`.
 
     Returns:
-        The live holder or target row whose state decides link visibility, or
-        `None` when no modeled uncertainty requires a deciding record.
+        The holder, target or connection row whose state decides link
+        visibility, or `None` when no modeled uncertainty requires a deciding
+        record.
     """
-    if (
-        not isinstance(link.get('type'), str)
-        or not isinstance(link.get('id'), int)
-        or not store.schema.declares(cast('str', link['type']))
-    ):
+    target = link_target(store, link)
+    if target is None or (target['type'], target['id']) == (holder['type'], holder['id']):
         return None
     if _listed(holder, field_name, link):
         return holder
-    target = store.row(cast('str', link['type']), cast('int', link['id']))
-    if target is None:
-        return None
-    edge = retirement_edge(store, holder, field_name, target)
-    if edge.effect == 'keep' and target['__retired']:
-        return holder
-    if (
-        edge.effect == 'hide'
-        and store.tainted(target)
-        and not cast('dict[str, FieldValue]', target['__taint']).get('active')
-    ):
+    if _uncertain(target):
         return target
+    if holder['__retired'] and connection_backed(holder, field_name, target):
+        record = connection_record(store, holder, field_name, target)
+        if record is not None and _uncertain(record):
+            return record
     return None
 
 
@@ -392,6 +517,11 @@ def hidden(
 ) -> bool:
     """Resolve observed link hiding under optional record-state assumptions.
 
+    A link is hidden while its target is retired, whether the holder is active
+    or retired. A retired holder also hides a connection-backed member while
+    the connection record is retired. A link to the holder itself stays
+    visible.
+
     Args:
         store: Site records used to resolve link targets.
         holder: Stored record containing the outgoing link.
@@ -402,39 +532,67 @@ def hidden(
 
     Returns:
         Whether the link is hidden under the observed rules and supplied
-        assumptions. Retired holders retain their links.
+        assumptions.
 
     Raises:
         MockgunError: If visibility depends on an uncertain record for which no
             explicit state was supplied.
     """
+    target = link_target(store, link)
+    if target is None or (target['type'], target['id']) == (holder['type'], holder['id']):
+        return False
     identity = (cast('str', holder['type']), cast('int', holder['id']))
     holder_state = assume.get(identity) if assume is not None else None
-    if holder_state.retired if holder_state is not None else holder['__retired']:
-        return False
+    retired = holder_state.retired if holder_state is not None else bool(holder['__retired'])
     deciding = deciding_record(store, holder, field_name, link)
     if deciding is not None:
         key = (cast('str', deciding['type']), cast('int', deciding['id']))
         state = assume.get(key) if assume is not None else None
         if state is None:
-            reason = store.tainted(deciding) or f'retired {link["type"]} {link["id"]} keep link'
-            raise MockgunError(f'{holder["type"]} {holder["id"]}.{field_name}: {reason}')
+            raise MockgunError(
+                f'{holder["type"]} {holder["id"]}.{field_name}: {store.tainted(deciding)}'
+            )
         if deciding is holder:
-            return (field_name, cast('str', link['type']), cast('int', link['id'])) in state.hidden
-        return state.retired
-    if (
-        not isinstance(link.get('type'), str)
-        or not isinstance(link.get('id'), int)
-        or not store.schema.declares(cast('str', link['type']))
-    ):
-        return False
-    target = store.row(cast('str', link['type']), cast('int', link['id']))
-    if target is None:
-        return False
-    edge = retirement_edge(store, holder, field_name, target)
-    hides = edge.effect == 'hide' or (holder['type'], field_name, target['type']) == (
-        'Version',
-        'entity',
-        'Shot',
-    )
-    return hides and bool(target['__retired'])
+            if not state.retired:
+                return (
+                    field_name,
+                    cast('str', link['type']),
+                    cast('int', link['id']),
+                ) in state.hidden
+            retired = True
+        elif not retired:
+            return state.retired
+    if retired:
+        return _retired_holder_hidden(store, holder, field_name, target, assume)
+    return _retired_target(target, assume)
+
+
+def named_link(store: Store, link: Mapping[str, FieldValue]) -> dict[str, FieldValue]:
+    """Return a detached identity with a name when the target is modeled.
+
+    Raises:
+        MockgunError: If the target's display name is unsettled.
+    """
+    result = {'type': link['type'], 'id': link['id']}
+    name = display_name(store, cast('str', link['type']), cast('int', link['id']))
+    if name is not None:
+        result['name'] = name
+    return result
+
+
+def retirement_edge(store: Store, holder: Row, field_name: str, target: Row) -> RetirementEdge:
+    """Resolve a retirement edge, including its observed holder conditions."""
+    kind = cast('str', holder['type'])
+    target_type = cast('str', target['type'])
+    if kind == 'EventLogEntry' and field_name == 'entity':
+        return RetirementEdge('hide')
+    rule = _RETIREMENT_EDGES.get((kind, field_name, target_type))
+    if rule is None:
+        return RetirementEdge('taint')
+    if rule.condition == 'note_links':
+        return _note_edge(store, holder, target)
+    if rule.condition == 'tasks':
+        return _task_note_edge(store, holder, rule)
+    if rule.condition == 'note_project' and (holder.get('note_links') or holder.get('tasks')):
+        return RetirementEdge('taint')
+    return RetirementEdge(rule.effect, rule.touched, rule.settled)