@software-dlc/cli 0.157.2

package/dist/local/local-org.js

@@ -0,0 +1,855 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { accountablePerson, checkBinding, checkHold, checkRelease, escalate, gateBoundPosts, governingPosts, mayGovern, positionLines, readOrgStructure, reportingLine, resolveSlot, resolveSlots, slotBinding, slotBindings } from '@software-dlc/graph/computation';
+import { validateGovernanceNodes } from '@software-dlc/graph/validator';
+import { gitCommonDir, locateRepository } from './app-shell-readers.js';
+import { LocalWorkspaceGraphStore, resolveLocalRepositoryStateDirectory } from './workspace-graph-store.js';
+import { LocalWorkspaceStore } from './workspace-store.js';
+/**
+ * The local org (org-structure-and-access.md, Local org without an org
+ * connection; osa-local-org): a workspace with no org connection plans a
+ * theoretical org whose posts its local person and local agents hold. Its
+ * definitions are a governance graph in the repository store, never a project
+ * graph, and its holders are rows beside it (local-org-store.ts). Every
+ * answer comes from the shared resolution in @software-dlc/graph/computation,
+ * so local and hosted orgs cannot disagree.
+ */
+/** The local Home's pseudo-org id (app-shell-readers.ts); one local org per repository store. */
+export const LOCAL_ORG_ID = 'local';
+/** The person running locally, as workflow.json names them. */
+export const LOCAL_PERSON = { id: 'user', kind: 'person' };
+const KEY = /^[a-z][a-z0-9_-]{0,63}$/;
+const MEMBER_ID = /^[a-z][a-z0-9_-]{0,63}$/;
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** The roles, holders and gates of a workflow.json (scripts/agent-coordination/workflow.json). */
+export function parseWorkflowRoles(value) {
+    if (!isRecord(value) || !Array.isArray(value.roles)) {
+        throw new Error('The workflow has no roles list.');
+    }
+    const roles = value.roles.map((role) => {
+        if (!isRecord(role) ||
+            typeof role.key !== 'string' ||
+            !KEY.test(role.key)) {
+            throw new Error(`The workflow role ${JSON.stringify(role)} has no valid key.`);
+        }
+        return {
+            key: role.key,
+            name: typeof role.name === 'string' && role.name.trim()
+                ? role.name
+                : role.key,
+            ...(typeof role.description === 'string'
+                ? { description: role.description }
+                : {})
+        };
+    });
+    const holders = {};
+    const holder_kinds = {};
+    if (isRecord(value.holders)) {
+        for (const [role, list] of Object.entries(value.holders)) {
+            if (!Array.isArray(list))
+                continue;
+            holder_kinds[role] = list.flatMap((holder) => isRecord(holder) && typeof holder.kind === 'string' ? [holder.kind] : []);
+            holders[role] = list.flatMap((holder) => isRecord(holder) &&
+                (holder.kind === 'person' || holder.kind === 'agent') &&
+                typeof holder.id === 'string'
+                ? [{ id: holder.id, kind: holder.kind }]
+                : []);
+        }
+    }
+    const gates = (Array.isArray(value.phases) ? value.phases : []).flatMap((phase) => isRecord(phase) && Array.isArray(phase.gates)
+        ? phase.gates.flatMap((gate) => isRecord(gate) &&
+            typeof gate.gate === 'string' &&
+            typeof gate.role === 'string'
+            ? [{ gate: gate.gate, role: gate.role }]
+            : [])
+        : []);
+    return { roles, holders, holder_kinds, gates };
+}
+/**
+ * The roles whose gates need a person: a role that holds a gate and has a
+ * holder other than an agent (a person or a team), the rule
+ * planning_gate.derive_approvals gives the user a gate by.
+ */
+export function personGateRoles(workflow) {
+    return new Set(workflow.gates
+        .map((gate) => gate.role)
+        .filter((role) => (workflow.holder_kinds[role] ?? []).some((kind) => kind !== 'agent')));
+}
+/** A role held only by people or teams, whose seeded function requires a person. */
+function heldByPeopleOnly(workflow, role) {
+    const kinds = workflow.holder_kinds[role] ?? [];
+    return kinds.length > 0 && kinds.every((kind) => kind !== 'agent');
+}
+/**
+ * The holder rules a local org checks: the gate slots are the slots keyed by
+ * a person-gate role, and the posts the project's overrides bind to one
+ * decide that gate too (osa_slots_ac_4).
+ */
+export function localOrgRules(graph, workflow, overrides = []) {
+    const roles = workflow ? personGateRoles(workflow) : new Set();
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const gate_slot_ids = new Set([...structure.slots.values()]
+        .filter((slot) => roles.has(slot.key))
+        .map((slot) => slot.id));
+    const gate_post_ids = gateBoundPosts(overrides, { gate_slot_ids });
+    return gate_post_ids.size
+        ? { gate_slot_ids, gate_post_ids }
+        : { gate_slot_ids };
+}
+/** A governance key made from a name: lowercase, dashes for other characters, starting with a letter. */
+export function keyFromName(name) {
+    const key = name
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^[^a-z]+/, '')
+        .replace(/-+$/, '')
+        .slice(0, 64);
+    return KEY.test(key) ? key : 'org';
+}
+function definitionNode(type, input, data = {}) {
+    return {
+        id: randomUUID(),
+        type,
+        ...(input.parent_id ? { parentId: input.parent_id } : {}),
+        data: {
+            data: {
+                label: input.label,
+                ...(input.description ? { description: input.description } : {}),
+                [type]: { key: input.key, ...data }
+            }
+        }
+    };
+}
+function relationship(source, target, type) {
+    return {
+        id: randomUUID(),
+        source,
+        target,
+        data: { data: { type } }
+    };
+}
+function keyOf(node) {
+    const domain = node.data
+        ?.data;
+    const data = domain?.[node.type];
+    return isRecord(data) && typeof data.key === 'string' ? data.key : undefined;
+}
+function labelOf(node) {
+    const label = node?.data?.data
+        ?.label;
+    return typeof label === 'string' ? label : '';
+}
+function findByKey(graph, type, key) {
+    return graph.nodes.find((node) => node.type === type && keyOf(node) === key);
+}
+const NOUN = {
+    team: 'team',
+    job_function: 'job function',
+    slot: 'slot'
+};
+function requireByKey(graph, type, key) {
+    const node = findByKey(graph, type, key);
+    if (!node)
+        throw new Error(`The local org has no ${NOUN[type]} ${key}.`);
+    return node;
+}
+/** Refuses a graph the governance validator reports broken, naming each problem. */
+function checked(graph) {
+    const broken = validateGovernanceNodes(graph.nodes, graph.edges).filter((issue) => issue.status === 'broken');
+    if (broken.length) {
+        throw new Error(`The local org would be invalid: ${broken.map((issue) => issue.message).join('; ')}.`);
+    }
+    return graph;
+}
+function withDefinition(graph, type, key, build) {
+    if (!KEY.test(key)) {
+        throw new Error(`${key} is not a key: use lowercase letters, digits, _ and -, starting with a letter.`);
+    }
+    if (findByKey(graph, type, key))
+        throw new Error(`The local org already has a ${NOUN[type]} ${key}.`);
+    const added = build();
+    return checked({
+        ...graph,
+        nodes: [...graph.nodes, ...added.nodes],
+        edges: [...graph.edges, ...added.edges]
+    });
+}
+export function addTeam(graph, input) {
+    return withDefinition(graph, 'team', input.key, () => {
+        const parent_id = input.parent
+            ? requireByKey(graph, 'team', input.parent).id
+            : undefined;
+        return {
+            nodes: [
+                definitionNode('team', {
+                    ...input,
+                    label: input.label ?? input.key,
+                    parent_id
+                })
+            ],
+            edges: []
+        };
+    });
+}
+export function addJobFunction(graph, input) {
+    return withDefinition(graph, 'job_function', input.key, () => {
+        const parent_id = input.parent
+            ? requireByKey(graph, 'job_function', input.parent).id
+            : undefined;
+        const slots = [...new Set(input.fills ?? [])].map((key) => requireByKey(graph, 'slot', key));
+        const node = definitionNode('job_function', { ...input, label: input.label ?? input.key, parent_id }, {
+            ...(input.requires_person ? { requires_person: true } : {}),
+            ...(input.escalable === false ? { escalable: false } : {})
+        });
+        return {
+            nodes: [node],
+            edges: slots.map((slot) => relationship(node.id, slot.id, 'fills'))
+        };
+    });
+}
+export function addSlot(graph, input) {
+    return withDefinition(graph, 'slot', input.key, () => ({
+        nodes: [
+            definitionNode('slot', { ...input, label: input.label ?? input.key })
+        ],
+        edges: []
+    }));
+}
+/** A post's name: its team's key and its job function's key, `team/function`. */
+export function postName(graph, structure, post_id) {
+    const post = structure.posts.get(post_id);
+    if (!post)
+        return post_id;
+    return `${structure.teams.get(post.team_id)?.key}/${structure.functions.get(post.function_id)?.key}`;
+}
+function splitPostName(name) {
+    const parts = name.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`${name} is not a post: name it <team>/<function>.`);
+    }
+    return [parts[0], parts[1]];
+}
+/** The post a name means; an unknown team, function or post is refused. */
+export function postIdOf(graph, structure, name) {
+    const [team_key, function_key] = splitPostName(name);
+    const team = requireByKey(graph, 'team', team_key);
+    const job = requireByKey(graph, 'job_function', function_key);
+    const post = [...structure.posts.values()].find((entry) => entry.team_id === team.id && entry.function_id === job.id);
+    if (!post)
+        throw new Error(`The local org has no post ${name}: add it with sdlc org add post ${name}.`);
+    return post.id;
+}
+export function addPost(graph, input) {
+    const [team_key, function_key] = splitPostName(input.name);
+    const team = requireByKey(graph, 'team', team_key);
+    const job = requireByKey(graph, 'job_function', function_key);
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    if ([...structure.posts.values()].some((post) => post.team_id === team.id && post.function_id === job.id)) {
+        throw new Error(`The local org already has a post ${input.name}.`);
+    }
+    const node = {
+        id: randomUUID(),
+        type: 'post',
+        parentId: team.id,
+        data: {
+            data: { label: input.label ?? `${labelOf(job)} (${labelOf(team)})` }
+        }
+    };
+    return checked({
+        ...graph,
+        nodes: [...graph.nodes, node],
+        edges: [...graph.edges, relationship(node.id, job.id, 'instantiates')]
+    });
+}
+function emptyGraph() {
+    return {
+        nodes: [],
+        edges: [],
+        tags: [],
+        paths: [],
+        path_relations: []
+    };
+}
+function refusalText(graph, structure, post_id, refusal) {
+    const name = postName(graph, structure, post_id);
+    if (refusal === 'person_required')
+        return `${name} needs a person: its job function requires one`;
+    if (refusal === 'gate_needs_person')
+        return `${name} decides a gate, so a person must hold it beside any agent`;
+    return `${name} already has a holder: a post with reports has one holder per team`;
+}
+/**
+ * Throws, naming each reason, unless `member` may take the post: the shared
+ * holder rules, and one id per member across people and agents.
+ */
+export function assertMayHold(graph, holders, post_id, member, rules) {
+    if (!MEMBER_ID.test(member.id)) {
+        throw new Error(`${member.id} is not a member id: use lowercase letters, digits, _ and -, starting with a letter.`);
+    }
+    const other = holders.find((holder) => holder.member.id === member.id && holder.member.kind !== member.kind);
+    if (other) {
+        throw new Error(`${member.id} already holds a post as ${other.member.kind === 'person' ? 'a person' : 'an agent'}.`);
+    }
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const refusals = checkHold(structure, holders, post_id, member, rules);
+    if (refusals.length) {
+        throw new Error(`Refused: ${refusals.map((refusal) => refusalText(graph, structure, post_id, refusal)).join('; ')}.`);
+    }
+}
+export function assertMayRelease(graph, holders, post_id, member, rules) {
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    if (!holders.some((holder) => holder.post_id === post_id &&
+        holder.member.id === member.id &&
+        holder.member.kind === member.kind)) {
+        throw new Error(`${member.id} does not hold ${postName(graph, structure, post_id)}.`);
+    }
+    const refusals = checkRelease(structure, holders, post_id, member.id, rules);
+    if (refusals.length) {
+        throw new Error(`Refused: ${refusals.map((refusal) => refusalText(graph, structure, post_id, refusal)).join('; ')}.`);
+    }
+}
+/**
+ * Throws, naming each post, when a post whose function has child functions
+ * has more than one holder: a graph edit, not only a hold, can make one so.
+ */
+export function assertOneHolderWithReports(graph, holders) {
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const parents = new Set([...structure.functions.values()].flatMap((job) => job.parent_id ? [job.parent_id] : []));
+    const crowded = [...structure.posts.values()].filter((post) => parents.has(post.function_id) &&
+        new Set(holders
+            .filter((holder) => holder.post_id === post.id)
+            .map((holder) => `${holder.member.kind}:${holder.member.id}`)).size > 1);
+    if (crowded.length) {
+        throw new Error(`Refused: a post with reports has one holder per team, and ${crowded
+            .map((post) => postName(graph, structure, post.id))
+            .join(', ')} would have reports with several holders; release all but one first.`);
+    }
+}
+/** The seeded org's top job function, which the local person holds. */
+export const ORG_LEAD = 'org-lead';
+/**
+ * A local org planned from a workflow's roles (osa_local_ac_1): a root team
+ * named for the org; an org lead function, held by the local person, so each
+ * agent's line reaches a person (OSA-07); for each role a slot and a job
+ * function filling it under the org lead, with a post in the root team; and
+ * the workflow's people and agents holding those posts. A role held only by
+ * people or teams seeds a function that requires a person.
+ */
+export function seedLocalOrg(workflow, org, held_since = new Date().toISOString()) {
+    if (workflow.roles.some((role) => role.key === ORG_LEAD)) {
+        throw new Error(`The workflow has a role ${ORG_LEAD}, which the seed keeps for the org's top function; rename it to seed.`);
+    }
+    const team = keyFromName(org.name);
+    let graph = addTeam(emptyGraph(), { key: team, label: org.name });
+    graph = addJobFunction(graph, {
+        key: ORG_LEAD,
+        label: 'Org lead',
+        description: 'Accountable for the local org; every role reports here.',
+        requires_person: true
+    });
+    graph = addPost(graph, { name: `${team}/${ORG_LEAD}` });
+    for (const role of workflow.roles) {
+        graph = addSlot(graph, {
+            key: role.key,
+            label: role.name,
+            description: role.description
+        });
+        graph = addJobFunction(graph, {
+            key: role.key,
+            label: role.name,
+            description: role.description,
+            parent: ORG_LEAD,
+            fills: [role.key],
+            requires_person: heldByPeopleOnly(workflow, role.key)
+        });
+        graph = addPost(graph, { name: `${team}/${role.key}` });
+    }
+    const rules = localOrgRules(graph, workflow);
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const holders = [
+        {
+            post_id: postIdOf(graph, structure, `${team}/${ORG_LEAD}`),
+            member: LOCAL_PERSON,
+            held_since
+        }
+    ];
+    // People first, so a gate post an agent shares already has its person.
+    for (const kind of ['person', 'agent']) {
+        for (const role of workflow.roles) {
+            const post_id = postIdOf(graph, structure, `${team}/${role.key}`);
+            for (const member of workflow.holders[role.key] ?? []) {
+                if (member.kind !== kind)
+                    continue;
+                if (holders.some((holder) => holder.post_id === post_id && holder.member.id === member.id))
+                    continue;
+                assertMayHold(graph, holders, post_id, member, rules);
+                holders.push({ post_id, member, held_since });
+            }
+        }
+    }
+    return { graph, holders };
+}
+function lineName(graph, structure, line) {
+    if (line.kind === 'top')
+        return 'top';
+    if (line.kind === 'post')
+        return postName(graph, structure, line.post_id);
+    return {
+        vacant: structure.functions.get(line.function_id)?.key ?? line.function_id
+    };
+}
+function slotSummary(graph, structure, resolution) {
+    const slot = structure.slots.get(resolution.slot_id)?.key ?? resolution.slot_id;
+    if (resolution.status === 'uncovered')
+        return { slot, status: resolution.status };
+    if (resolution.status === 'vacant') {
+        return {
+            slot,
+            status: resolution.status,
+            posts: resolution.post_ids.map((id) => postName(graph, structure, id))
+        };
+    }
+    return {
+        slot,
+        status: resolution.status,
+        posts: resolution.posts.map((entry) => ({
+            post: postName(graph, structure, entry.post_id),
+            holders: entry.holders
+        })),
+        ...(resolution.needs_person ? { needs_person: true } : {})
+    };
+}
+/** How each slot resolves (osa_local_ac_3), or one slot by key; an unknown slot or team is refused. */
+export function resolveLocalSlots(graph, holders, rules, input = {}) {
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const team_id = input.team
+        ? requireByKey(graph, 'team', input.team).id
+        : undefined;
+    const resolutions = input.slot
+        ? [
+            resolveSlot(structure, holders, requireByKey(graph, 'slot', input.slot).id, team_id, rules)
+        ]
+        : resolveSlots(structure, holders, team_id, rules);
+    return resolutions.map((resolution) => slotSummary(graph, structure, resolution));
+}
+/** The whole local org: definitions, posts with their holders and lines, members' positions, and slots. */
+export function describeLocalOrg(graph, holders, rules) {
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+    const keyFor = (id) => id ? (keyOf(nodes.get(id)) ?? id) : null;
+    const members = new Map();
+    for (const holder of holders)
+        members.set(`${holder.member.kind}:${holder.member.id}`, holder.member);
+    return {
+        teams: [...structure.teams.values()].map((team) => ({
+            key: team.key,
+            label: labelOf(nodes.get(team.id)),
+            parent: keyFor(team.parent_id)
+        })),
+        job_functions: [...structure.functions.values()].map((job) => ({
+            key: job.key,
+            label: labelOf(nodes.get(job.id)),
+            parent: keyFor(job.parent_id),
+            fills: job.fills.map((id) => structure.slots.get(id)?.key ?? id),
+            requires_person: job.requires_person,
+            escalable: job.escalable
+        })),
+        slots: [...structure.slots.values()].map((slot) => ({
+            key: slot.key,
+            label: labelOf(nodes.get(slot.id)),
+            gate: rules.gate_slot_ids?.has(slot.id) ?? false
+        })),
+        posts: [...structure.posts.values()].map((post) => ({
+            post: postName(graph, structure, post.id),
+            label: labelOf(nodes.get(post.id)),
+            reports_to: lineName(graph, structure, reportingLine(structure, post.id)),
+            holders: holders
+                .filter((holder) => holder.post_id === post.id)
+                .map((holder) => ({ ...holder.member, held_since: holder.held_since }))
+        })),
+        members: [...members.values()]
+            .sort((a, b) => a.kind.localeCompare(b.kind) || a.id.localeCompare(b.id))
+            .map((member) => {
+            const own = holders.filter((holder) => holder.member.kind === member.kind);
+            const lines = positionLines(structure, own, member.id);
+            const accountable = member.kind === 'agent'
+                ? accountablePerson(structure, holders, member.id)
+                : null;
+            return {
+                ...member,
+                posts: lines.map((line) => ({
+                    post: postName(graph, structure, line.post_id),
+                    reports_to: lineName(graph, structure, line.reports_to),
+                    primary: line.primary,
+                    dotted: line.dotted
+                })),
+                ...(member.kind === 'agent'
+                    ? { accountable_person: accountable }
+                    : {})
+            };
+        }),
+        slot_resolution: resolveSlots(structure, holders, undefined, rules).map((resolution) => slotSummary(graph, structure, resolution))
+    };
+}
+export async function openLocalOrgRepository(input) {
+    const common = await gitCommonDir(input.cwd);
+    if (!common)
+        throw new Error('sdlc org runs in a Git repository.');
+    const state_dir = resolveLocalRepositoryStateDirectory({
+        git_common_dir: common,
+        override: input.state_dir
+    });
+    const location = await locateRepository(common);
+    const checkout = await gitTopLevel(input.cwd);
+    const store = await LocalWorkspaceStore.open({
+        state_dir,
+        git_common_dir: common
+    });
+    return {
+        store,
+        graphs: new LocalWorkspaceGraphStore(state_dir),
+        name: 'name' in location && location.name ? location.name : 'repository',
+        checkout
+    };
+}
+/** The checkout at `cwd`, or null with no work tree (a bare repository, or inside .git). */
+function gitTopLevel(cwd) {
+    return new Promise((done) => {
+        execFile('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', timeout: 10_000 }, (error, stdout) => done(error ? null : String(stdout).trim() || null));
+    });
+}
+export async function readWorkflowRoles(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    return parseWorkflowRoles(JSON.parse(text));
+}
+/** Where workflow.json is read by default; null with no work tree, which has no default workflow. */
+export function defaultWorkflowPath(repository) {
+    return repository.checkout
+        ? join(repository.checkout, 'scripts', 'agent-coordination', 'workflow.json')
+        : null;
+}
+/**
+ * The org's graph, holders, and its project's stored owning team and slot
+ * overrides, or null when it has no graph yet.
+ */
+export async function readLocalOrg(repository) {
+    const root = repository.store.org.root(LOCAL_ORG_ID);
+    if (!root)
+        return null;
+    return {
+        root,
+        graph: await repository.graphs.readGraph(root),
+        holders: repository.store.org.holders(LOCAL_ORG_ID),
+        project_team: repository.store.org.projectTeam(LOCAL_ORG_ID),
+        overrides: repository.store.org.overrides(LOCAL_ORG_ID)
+    };
+}
+const NO_ORG = 'This repository has no local org yet: plan one with sdlc org seed, or start one with sdlc org add team <key>.';
+/**
+ * Changes the org's graph: writes the new graph object, then moves the root
+ * from the one read with a check-and-set, under the object store lock so a
+ * prune cannot remove the object in between. `seed` writes holders too, and
+ * only into an org with no graph.
+ */
+export async function changeLocalOrg(repository, change) {
+    return repository.graphs.withObjectStoreLock('local-org', async () => {
+        const before = repository.store.org.root(LOCAL_ORG_ID);
+        const next = change(before ? await repository.graphs.readGraph(before) : null);
+        const root = await repository.graphs.writeGraph(next.graph);
+        repository.store.org.write(() => {
+            repository.store.org.setRoot(LOCAL_ORG_ID, before, root);
+            for (const holder of next.holders ?? [])
+                repository.store.org.addHolder(LOCAL_ORG_ID, holder);
+            // A definition change can give a held post reports: check the
+            // holders as they stand, in the same transaction (osa_structure_ac_3).
+            assertOneHolderWithReports(next.graph, repository.store.org.holders(LOCAL_ORG_ID));
+        });
+        return { root, graph: next.graph };
+    });
+}
+/** Adds to an existing org's graph, or starts one with its first team. */
+export function onOrg(graph, starts_org) {
+    if (graph)
+        return graph;
+    if (!starts_org)
+        throw new Error(NO_ORG);
+    return emptyGraph();
+}
+/**
+ * Changes who holds a post: checks the post and the rules against the graph
+ * and holders as they stand, inside one write transaction, so two holds
+ * cannot both pass a one-holder rule.
+ */
+export async function changeLocalHolder(repository, input) {
+    const root = repository.store.org.root(LOCAL_ORG_ID);
+    if (!root)
+        throw new Error(NO_ORG);
+    const graph = await repository.graphs.readGraph(root);
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const post_id = postIdOf(graph, structure, input.post);
+    return repository.store.org.write(() => {
+        if (repository.store.org.root(LOCAL_ORG_ID) !== root) {
+            throw new Error('The local org changed while this command ran; run it again.');
+        }
+        const holders = repository.store.org.holders(LOCAL_ORG_ID);
+        const rules = localOrgRules(graph, input.workflow, repository.store.org.overrides(LOCAL_ORG_ID));
+        if (input.action === 'hold') {
+            if (holders.some((holder) => holder.post_id === post_id &&
+                holder.member.id === input.member.id &&
+                holder.member.kind === input.member.kind)) {
+                return { post: input.post, member: input.member, changed: false };
+            }
+            assertMayHold(graph, holders, post_id, input.member, rules);
+            repository.store.org.addHolder(LOCAL_ORG_ID, {
+                post_id,
+                member: input.member,
+                held_since: new Date().toISOString()
+            });
+        }
+        else {
+            assertMayRelease(graph, holders, post_id, input.member, rules);
+            repository.store.org.removeHolder(LOCAL_ORG_ID, post_id, input.member);
+        }
+        return { post: input.post, member: input.member, changed: true };
+    });
+}
+/**
+ * The repository's owning team (osa-slots): the repository is its local
+ * org's one project, owned by the team sdlc org own named, or else by the
+ * org's only root team.
+ */
+export function projectTeamId(structure, stored) {
+    const owner = projectOwner(structure, stored);
+    if ('team_id' in owner)
+        return owner.team_id;
+    throw new Error(owner.roots.length
+        ? `The local org has several root teams (${owner.roots.join(', ')}): name the repository's owning team with sdlc org own <team>.`
+        : 'The local org has no team yet: add one with sdlc org add team <key>.');
+}
+/**
+ * The owning team, or, when none owns the project, the root team keys
+ * sdlc org own chooses from (none when the org has no team).
+ */
+export function projectOwner(structure, stored) {
+    if (stored && structure.teams.has(stored))
+        return { team_id: stored };
+    const roots = [...structure.teams.values()].filter((team) => team.parent_id === null);
+    if (roots.length === 1)
+        return { team_id: roots[0].id };
+    return { roots: roots.map((team) => team.key).sort() };
+}
+/** A member named as `person:<id>` or `agent:<id>`. */
+export function parseMember(text) {
+    const [kind, id, ...rest] = text.split(':');
+    if ((kind !== 'person' && kind !== 'agent') || !id || rest.length) {
+        throw new Error(`${text} is not a member: name it person:<id> or agent:<id>.`);
+    }
+    return { id, kind };
+}
+function memberText(member) {
+    return `${member.kind}:${member.id}`;
+}
+function describeBinding(graph, structure, binding) {
+    return {
+        slot: structure.slots.get(binding.slot_id)?.key ?? binding.slot_id,
+        source: binding.source,
+        status: binding.status,
+        posts: binding.posts.map((entry) => ({
+            post: postName(graph, structure, entry.post_id),
+            holders: entry.holders,
+            ...(entry.off_description ? { off_description: true } : {})
+        })),
+        ...(binding.needs_person ? { needs_person: true } : {}),
+        ...(binding.reason !== undefined
+            ? {
+                reason: binding.reason,
+                ...(binding.set_by ? { set_by: memberText(binding.set_by) } : {}),
+                ...(binding.set_at ? { set_at: binding.set_at } : {})
+            }
+            : {}),
+        ...(binding.stale_post_ids
+            ? { stale_posts: binding.stale_post_ids.length }
+            : {})
+    };
+}
+/**
+ * The repository project's owning team and each slot's binding, or one slot
+ * by key (osa_slots_ac_1 to ac_3, ac_9); an unknown slot is refused.
+ */
+export function describeLocalProject(org, rules, input = {}) {
+    const structure = readOrgStructure(org.graph.nodes, org.graph.edges);
+    const team_id = projectTeamId(structure, org.project_team);
+    return describeProjectOf(org, structure, team_id, rules, input);
+}
+/**
+ * The org chart's project (osa-slots-viewer, osa_slots_ac_10): its owning
+ * team and each slot's binding, or the root teams to choose an owner from.
+ */
+export function describeLocalProjectOrOwners(org, rules) {
+    const structure = readOrgStructure(org.graph.nodes, org.graph.edges);
+    const owner = projectOwner(structure, org.project_team);
+    if ('roots' in owner)
+        return { team: null, roots: owner.roots };
+    return describeProjectOf(org, structure, owner.team_id, rules);
+}
+function describeProjectOf(org, structure, team_id, rules, input = {}) {
+    const bindings = input.slot
+        ? [
+            slotBinding(structure, org.holders, requireByKey(org.graph, 'slot', input.slot).id, team_id, org.overrides, rules)
+        ]
+        : slotBindings(structure, org.holders, team_id, org.overrides, rules);
+    return {
+        team: structure.teams.get(team_id).key,
+        slots: bindings.map((binding) => describeBinding(org.graph, structure, binding))
+    };
+}
+/** Who decides a slot's gate when its holders are absent or the author (osa_slots_ac_5). */
+export function escalateLocalSlot(org, rules, input) {
+    const structure = readOrgStructure(org.graph.nodes, org.graph.edges);
+    const team_id = projectTeamId(structure, org.project_team);
+    const slot_id = requireByKey(org.graph, 'slot', input.slot).id;
+    const binding = slotBinding(structure, org.holders, slot_id, team_id, org.overrides, rules);
+    const result = escalate(structure, org.holders, binding, input, rules);
+    const names = (ids) => ids.map((id) => postName(org.graph, structure, id));
+    if (result.kind === 'decides') {
+        return {
+            slot: input.slot,
+            decides: {
+                post: postName(org.graph, structure, result.post_id),
+                members: result.members,
+                escalated: result.escalated,
+                path: names(result.path)
+            }
+        };
+    }
+    if (result.kind === 'waits') {
+        return {
+            slot: input.slot,
+            waits_for: structure.functions.get(result.function_id)?.key,
+            why: 'its job function is not escalable, so only a holder of that function decides'
+        };
+    }
+    return {
+        slot: input.slot,
+        unresolved: true,
+        path: names(result.path),
+        why: binding.status === 'uncovered'
+            ? 'no post fills the slot'
+            : 'nobody eligible holds a post up the reporting line'
+    };
+}
+/** Throws unless `actor` holds a post governing the team's projects (osa_slots_ac_8). */
+function assertMayGovern(graph, structure, holders, team_id, actor) {
+    if (mayGovern(structure, holders, team_id, actor))
+        return;
+    const posts = governingPosts(structure, team_id).map((id) => postName(graph, structure, id));
+    throw new Error(`Refused: ${memberText(actor)} holds no post that governs team ${structure.teams.get(team_id)?.key}'s projects; ${posts.length
+        ? `a holder of ${posts.join(' or ')} decides`
+        : 'the team and its parents have no post to govern them'}.`);
+}
+function bindingRefusalText(slot, refusal) {
+    return refusal === 'no_posts'
+        ? `name at least one post to bind ${slot} to`
+        : `${slot} holds a gate that needs a person, and one of those posts is held only by agents`;
+}
+/**
+ * Overrides a slot's binding with posts and a reason, or clears it back to
+ * the baseline, as `actor` (osa_slots_ac_2, ac_4, ac_8). Checked against the
+ * graph, holders and overrides as they stand, inside one write transaction.
+ */
+export async function changeLocalBinding(repository, input) {
+    const root = repository.store.org.root(LOCAL_ORG_ID);
+    if (!root)
+        throw new Error(NO_ORG);
+    const graph = await repository.graphs.readGraph(root);
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const slot_id = requireByKey(graph, 'slot', input.slot).id;
+    const post_ids = input.posts?.map((name) => postIdOf(graph, structure, name));
+    const reason = input.reason?.trim();
+    if (post_ids && !reason) {
+        throw new Error('Give the reason for the override with --reason <text>: an override is reported with it.');
+    }
+    return repository.store.org.write(() => {
+        if (repository.store.org.root(LOCAL_ORG_ID) !== root) {
+            throw new Error('The local org changed while this command ran; run it again.');
+        }
+        const holders = repository.store.org.holders(LOCAL_ORG_ID);
+        const project_team = repository.store.org.projectTeam(LOCAL_ORG_ID);
+        const team_id = projectTeamId(structure, project_team);
+        assertMayGovern(graph, structure, holders, team_id, input.actor);
+        const rules = localOrgRules(graph, input.workflow);
+        let changed;
+        if (post_ids) {
+            const refusals = checkBinding(structure, holders, slot_id, post_ids, rules);
+            if (refusals.length) {
+                throw new Error(`Refused: ${refusals.map((refusal) => bindingRefusalText(input.slot, refusal)).join('; ')}.`);
+            }
+            repository.store.org.setOverride(LOCAL_ORG_ID, {
+                slot_id,
+                post_ids,
+                reason: reason,
+                set_by: input.actor,
+                set_at: new Date().toISOString()
+            });
+            changed = true;
+        }
+        else {
+            changed = repository.store.org.clearOverride(LOCAL_ORG_ID, slot_id);
+        }
+        const org = {
+            graph,
+            holders,
+            project_team,
+            overrides: repository.store.org.overrides(LOCAL_ORG_ID)
+        };
+        return {
+            changed,
+            ...describeLocalProject(org, localOrgRules(graph, input.workflow, org.overrides), { slot: input.slot })
+        };
+    });
+}
+/**
+ * Names the team that owns the repository's project, as `actor`, who must
+ * govern both the team that owns it now and the new one (osa_slots_ac_8).
+ */
+export async function setLocalProjectTeam(repository, input) {
+    const root = repository.store.org.root(LOCAL_ORG_ID);
+    if (!root)
+        throw new Error(NO_ORG);
+    const graph = await repository.graphs.readGraph(root);
+    const structure = readOrgStructure(graph.nodes, graph.edges);
+    const team_id = requireByKey(graph, 'team', input.team).id;
+    return repository.store.org.write(() => {
+        if (repository.store.org.root(LOCAL_ORG_ID) !== root) {
+            throw new Error('The local org changed while this command ran; run it again.');
+        }
+        const holders = repository.store.org.holders(LOCAL_ORG_ID);
+        const stored = repository.store.org.projectTeam(LOCAL_ORG_ID);
+        let current = null;
+        try {
+            current = projectTeamId(structure, stored);
+        }
+        catch {
+            // Several root teams and no owner yet: only the new team governs.
+        }
+        if (current)
+            assertMayGovern(graph, structure, holders, current, input.actor);
+        assertMayGovern(graph, structure, holders, team_id, input.actor);
+        repository.store.org.setProjectTeam(LOCAL_ORG_ID, team_id);
+        return { team: input.team, changed: current !== team_id };
+    });
+}
+export { NO_ORG as LOCAL_ORG_MISSING };
+//# sourceMappingURL=local-org.js.map