zettelkasten.dashboard.backend.routes.organizations

zettelkasten.dashboard.backend.routes.organizations

Organization catalog + spine promote/demote/resync/verify/overlay routes.

Split out of the former flat routes.py; behaviour is unchanged.

SpineActionRequest

Bases: BaseModel

Optional knobs for promote/resync (sensible defaults when omitted).

Source code in zettelkasten/dashboard/backend/routes/organizations.py

class SpineActionRequest(BaseModel):
    """Optional knobs for promote/resync (sensible defaults when omitted)."""

    attach_relation: str = ""
    row_relation: str = ""
    link_relation: str = ""
    # Opt-in: also stamp each promoted member's dimension tag onto its base note.
    # Default OFF so promotion never mutates base notes unless explicitly asked.
    tag_stamp: bool = False

project_organizations

project_organizations(name: str) -> dict

List the organizations (saved matrix definitions) owned by a project.

Owner-level — spans every review scoped to this project. Listing also lazily migrates any legacy review tables into the registry (idempotent). This is the shared org/spine CATALOG the per-view spine selectors (graph/matrix/outline) read; default_spine names the project's primary org (the default lens) when one is pinned, so a view can default to it. Each org carries its state (lens vs materialized spine) + spine_ref so the selector can show only the materialized spines as overlay options.

Federation-aware read: a namespaced <repo_id>:<local> project reads the PEER's org catalog read-only (graphs_dir=repo.zettel_dir, migrate=False so the lazy migration WRITE never touches a peer), and its default_spine from the peer's project manifest. A local ref keeps the exact prior behavior.

Source code in zettelkasten/dashboard/backend/routes/organizations.py

@router.get("/projects/{name}/organizations")
def project_organizations(name: str) -> dict:
    """List the organizations (saved matrix definitions) owned by a project.

    Owner-level — spans every review scoped to this project. Listing also lazily
    migrates any legacy review tables into the registry (idempotent). This is the
    shared org/spine CATALOG the per-view spine selectors (graph/matrix/outline)
    read; ``default_spine`` names the project's primary org (the default lens)
    when one is pinned, so a view can default to it. Each org carries its ``state``
    (``lens`` vs materialized ``spine``) + ``spine_ref`` so the selector can show
    only the materialized spines as overlay options.

    Federation-aware read: a namespaced ``<repo_id>:<local>`` project reads the
    PEER's org catalog read-only (``graphs_dir=repo.zettel_dir``, ``migrate=False``
    so the lazy migration WRITE never touches a peer), and its ``default_spine``
    from the peer's project manifest. A local ref keeps the exact prior behavior.
    """
    local, repo = _resolve_ref(name)
    # P0: gate the federated OWNER before reading the peer store — a hidden project
    # (or one touching a disallowed source) 404s rather than leaking its catalog.
    _gate_federated_owner("project", name, local, repo)
    base = repo.zettel_dir if repo is not None else GRAPHS_DIR
    orgs = organizations.list_organizations(
        "project", local, graphs_dir=base, migrate=(repo is None)
    )
    default_spine = ""
    try:
        project_data = load_project(local, graphs_dir=base)
        default_spine = str(project_data.get("default_spine") or "") if isinstance(project_data, dict) else ""
    except (ValueError, FileNotFoundError, OSError):
        default_spine = ""
    return {"organizations": orgs, "default_spine": default_spine}

graph_organizations

graph_organizations(name: str) -> dict

List the organizations (saved matrix definitions) owned by a source graph.

Federation-aware read: a namespaced graph reads the PEER's org catalog read-only (graphs_dir=repo.zettel_dir, migrate=False); a local ref keeps the exact prior behavior.

Source code in zettelkasten/dashboard/backend/routes/organizations.py

@router.get("/graphs/{name}/organizations")
def graph_organizations(name: str) -> dict:
    """List the organizations (saved matrix definitions) owned by a source graph.

    Federation-aware read: a namespaced graph reads the PEER's org catalog
    read-only (``graphs_dir=repo.zettel_dir``, ``migrate=False``); a local ref
    keeps the exact prior behavior.
    """
    local, repo = _resolve_ref(name)
    # P0: gate the federated OWNER before reading the peer store — a hidden graph
    # 404s rather than leaking its org catalog.
    _gate_federated_owner("graph", name, local, repo)
    base = repo.zettel_dir if repo is not None else GRAPHS_DIR
    return {
        "organizations": organizations.list_organizations(
            "graph", local, graphs_dir=base, migrate=(repo is None)
        )
    }

promote_project_org async

promote_project_org(name: str, org_id: str, req: SpineActionRequest = SpineActionRequest()) -> dict

Materialize a project-owned org lens into a spine (+ bulk-attach members).

Source code in zettelkasten/dashboard/backend/routes/organizations.py

async def promote_project_org(name: str, org_id: str, req: SpineActionRequest = SpineActionRequest()) -> dict:
    """Materialize a project-owned org lens into a spine (+ bulk-attach members)."""
    return await _promote("project", name, org_id, req)

promote_graph_org async

promote_graph_org(name: str, org_id: str, req: SpineActionRequest = SpineActionRequest()) -> dict

Materialize a graph-owned org lens into a spine (+ bulk-attach members).

Source code in zettelkasten/dashboard/backend/routes/organizations.py

async def promote_graph_org(name: str, org_id: str, req: SpineActionRequest = SpineActionRequest()) -> dict:
    """Materialize a graph-owned org lens into a spine (+ bulk-attach members)."""
    return await _promote("graph", name, org_id, req)

demote_project_org

demote_project_org(name: str, org_id: str) -> dict

Demote a project-owned spine back to a lens (keeps nodes + edges).

Source code in zettelkasten/dashboard/backend/routes/organizations.py

def demote_project_org(name: str, org_id: str) -> dict:
    """Demote a project-owned spine back to a lens (keeps nodes + edges)."""
    return _demote("project", name, org_id)

demote_graph_org

demote_graph_org(name: str, org_id: str) -> dict

Demote a graph-owned spine back to a lens (keeps nodes + edges).

Source code in zettelkasten/dashboard/backend/routes/organizations.py

def demote_graph_org(name: str, org_id: str) -> dict:
    """Demote a graph-owned spine back to a lens (keeps nodes + edges)."""
    return _demote("graph", name, org_id)

resync_project_org async

resync_project_org(name: str, org_id: str, req: SpineActionRequest = SpineActionRequest()) -> dict

Incrementally route new in-scope notes into a project-owned spine.

Source code in zettelkasten/dashboard/backend/routes/organizations.py

async def resync_project_org(name: str, org_id: str, req: SpineActionRequest = SpineActionRequest()) -> dict:
    """Incrementally route new in-scope notes into a project-owned spine."""
    return await _resync("project", name, org_id, req)

resync_graph_org async

resync_graph_org(name: str, org_id: str, req: SpineActionRequest = SpineActionRequest()) -> dict

Incrementally route new in-scope notes into a graph-owned spine.

Source code in zettelkasten/dashboard/backend/routes/organizations.py

async def resync_graph_org(name: str, org_id: str, req: SpineActionRequest = SpineActionRequest()) -> dict:
    """Incrementally route new in-scope notes into a graph-owned spine."""
    return await _resync("graph", name, org_id, req)

delete_project_spine

delete_project_spine(name: str, org_id: str) -> dict

Transactional teardown of a project-owned spine (reverts the org to a lens).

Source code in zettelkasten/dashboard/backend/routes/organizations.py

def delete_project_spine(name: str, org_id: str) -> dict:
    """Transactional teardown of a project-owned spine (reverts the org to a lens)."""
    return _delete_spine("project", name, org_id)

delete_graph_spine

delete_graph_spine(name: str, org_id: str) -> dict

Transactional teardown of a graph-owned spine (reverts the org to a lens).

Source code in zettelkasten/dashboard/backend/routes/organizations.py

def delete_graph_spine(name: str, org_id: str) -> dict:
    """Transactional teardown of a graph-owned spine (reverts the org to a lens)."""
    return _delete_spine("graph", name, org_id)

verify_project_org

verify_project_org(name: str, org_id: str, semantic: bool = False) -> dict

Audit a project-owned org's synthesized summaries against their members.

?semantic=true opts into the agent over-reach tier (one call per synthesized cell); omitted, the audit is a free structural pass.

Source code in zettelkasten/dashboard/backend/routes/organizations.py

def verify_project_org(name: str, org_id: str, semantic: bool = False) -> dict:
    """Audit a project-owned org's synthesized summaries against their members.

    ``?semantic=true`` opts into the agent over-reach tier (one call per
    synthesized cell); omitted, the audit is a free structural pass.
    """
    return _verify_org("project", name, org_id, semantic=semantic)

verify_graph_org

verify_graph_org(name: str, org_id: str, semantic: bool = False) -> dict

Audit a graph-owned org's synthesized summaries against their members.

?semantic=true opts into the agent over-reach tier (one call per synthesized cell); omitted, the audit is a free structural pass.

Source code in zettelkasten/dashboard/backend/routes/organizations.py

def verify_graph_org(name: str, org_id: str, semantic: bool = False) -> dict:
    """Audit a graph-owned org's synthesized summaries against their members.

    ``?semantic=true`` opts into the agent over-reach tier (one call per
    synthesized cell); omitted, the audit is a free structural pass.
    """
    return _verify_org("graph", name, org_id, semantic=semantic)

project_spine_overlay

project_spine_overlay(name: str, org_id: str) -> dict

Load a project-owned spine's overlay (apex/dimensions/hubs) for GraphView.

Source code in zettelkasten/dashboard/backend/routes/organizations.py

def project_spine_overlay(name: str, org_id: str) -> dict:
    """Load a project-owned spine's overlay (apex/dimensions/hubs) for GraphView."""
    return _spine_overlay("project", name, org_id)

graph_spine_overlay

graph_spine_overlay(name: str, org_id: str) -> dict

Load a graph-owned spine's overlay (apex/dimensions/hubs) for GraphView.

Source code in zettelkasten/dashboard/backend/routes/organizations.py

def graph_spine_overlay(name: str, org_id: str) -> dict:
    """Load a graph-owned spine's overlay (apex/dimensions/hubs) for GraphView."""
    return _spine_overlay("graph", name, org_id)