mixle.substrate.spaces module

Team-scoped substrate views with explicit publishing.

The substrate tags every item with an access scope (“local”, a team id, or a shared scope like “public”), but the raw store filters on ONE scope at a time. A team’s real visibility is a union: its own items PLUS whatever has been shared into a common scope, and never another team’s private items. Space is that view. Construct one for a team and it answers retrieve / all over exactly the team’s visible set, so two teams querying the same substrate see different, correctly-isolated knowledge.

Sharing is explicit: nothing crosses a scope boundary until someone calls publish(). Publishing re-scopes an item into a shared scope and records who published it and from where.

visible_scopes(team, *, shared=(PUBLIC,))[source]

The scopes a team may read: its own id plus the shared scopes (never another team’s private one).

Parameters:
Return type:

set[str]

publish(substrate, ids, *, to=PUBLIC, by=None, from_scope=None)[source]

Share items into a common scope.

Re-scopes each item in ids to to and records published_by / published_from in its provenance. Returns the ids actually published (missing ids are skipped). from_scope, if given, guards that only items currently in that scope are published (an ACL check the caller can enforce).

Parameters:

  • substrate (Substrate)

  • ids (list[str])

  • to (str)

  • by (str | None)

  • from_scope (str | None)

Return type:

list[str]

version_of(item)[source]

The share version of an item (0 if never published) – a monotonic counter bumped by each publish.

Parameters:

item (Any)

Return type:

int

history(substrate, item_id)[source]

The full publish history of an item: every version with who shared it, from where, to where.

Parameters:

  • substrate (Substrate)

  • item_id (str)

Return type:

list[dict[str, Any]]

merge_versions(substrate, keep_id, other_id, *, by=None, prefer='latest')[source]

Reconcile two versions of the same knowledge into one, keeping full lineage (no silent loss, P2).

Merges other_id into keep_id: unions tags and links, keeps the text/payload of whichever has the higher version (prefer="latest") or of keep (prefer="keep"), bumps the surviving item’s version, records BOTH parents in the history, and removes the merged-away item. Returns the surviving id, or None if either is missing. Two teams that independently edited a shared item can be reconciled without either edit vanishing unrecorded.

Parameters:

  • substrate (Substrate)

  • keep_id (str)

  • other_id (str)

  • by (str | None)

  • prefer (str)

Return type:

str | None

class Space(substrate, team, *, shared=(PUBLIC,))[source]

Bases: object

A team’s scoped view over a shared substrate: its own items plus what has been shared to it.

Parameters:

  • substrate (Substrate)

  • team (str)

  • shared (tuple[str, ...])

property scopes: set[str]
all(*, kind=None)[source]

Every visible item (optionally of one kind) – never another team’s private knowledge.

Parameters:

kind (str | None)

Return type:

list[SubstrateItem]

add(*, scope=None, **kw)[source]

Add an item to this team’s own scope by default (pass scope=PUBLIC to share immediately).

Parameters:
Return type:

str

retrieve(query, *, k=8, **kw)[source]

Retrieve over exactly the team’s visible set (own scope ∪ shared), with cross-kind diversity.

Parameters:
Return type:

Any

publish(ids, *, to=PUBLIC, by=None)[source]

Share this team’s items into a common scope (audited). Only own-scope items are publishable.

Parameters:
Return type:

list[str]