Skip to content

Publication and record ownership

Publication releases information to a defined audience. It changes what an admitted reader can see through that channel. It does not by itself change the accepted agreement, approve completed work or create invoice authority. The project continues to connect records whose owners and lifecycles remain separate.

Toolora uses several publication mechanisms. A customer presentation has editorial revisions; customer planning has immutable snapshots; worker instructions and several files use current rows with audience flags or explicit links. There is no single publication status that releases the whole project to every audience.

Channel Owning source and released representation Admission and withdrawal
Customer presentation project_presentation_versions: bounded editorial JSON, source digest and one current published customer revision Customer project admission still applies. A new publication archives its predecessor. No standalone unpublish endpoint exists in the reviewed presentation API.
Customer planning project_planning_publications: versioned promise dates and selected customer-facing passes Portal reads only the latest non-withdrawn snapshot. Withdrawal hides that latest plan; it does not restore an earlier version.
Customer work-order summary and daily log Current non-deleted rows filtered by is_visible_to_customer Customer project admission plus each row’s visibility. These reads are current projections, not presentation revisions.
Worker order and personal schedule Current order is_published_to_worker, own pass is_published_to_worker, exact assignments and effective project scope Worker identity, company and assignment still apply. Clearing publication removes delivery through the corresponding projection; action permissions have separate rules.
UE order and pass Request/commitment-scoped orders, is_visible_to_ue and own commitment passes is_published_to_ue Executor/request scope and publication are checked by the named surface. Commitment closure is not universal revocation.
Customer file entity_files.is_visible_to_customer, verified content and canonical project Storage path Future customer reads/signing exclude a withdrawn file. Previously issued signed URLs or downloaded bytes are not recalled.
Worker file Approved, unrevoked work_order_file_links to an exact published assigned order The link can be revoked independently of the project file and customer visibility.
Conversation message/attachment Conversation type, owner, participants and project/order/commitment audience A saved message follows that conversation’s access rules. It is not an editorial release and does not automatically publish its attachment as a project image.

Customer portal access owns customer admission under the shared discovery/detail contract. Publication and operation-specific permissions remain separate. Worker and subcontractor access owns assignment, delivery and action predicates. The UE project-file loader still has a broader project-wide read without an audience/content-validity filter. This article does not imply that publishing a principal’s file is required by that existing UE path. Conversation audiences and file lifecycle remain separate owners.

A presentation contains a title, introduction, next step, palette, sections, media references and an optional description. The API rejects unknown fields rather than accepting prices, acceptance or payment fields in the editorial JSON. Canonical commercial and financial records remain the owners of those facts.

Saving creates a new draft revision and archives an earlier draft. It leaves the published revision visible. The current API always sends p_expected_version_id, including null for an editor that saw no version. The nine-argument save RPC locks the project, checks the latest version across draft, published and archived rows, and returns conflict when another version was saved first. Idempotent retries return the existing saved result. The eight-argument compatibility overload still exists for an older API and does not provide this expected-version check.

Publishing requires projects:write, same-company project scope and a staff person. The route reevaluates editorial completeness, current template revision, traceable price/scope, source ambiguity, historical billing exceptions and media references. “Ready to publish” means those presentation checks passed. It does not mean the source offer has been accepted. A reconciled imported source can support a presentation while its agreement remains unproven.

The publish RPC serializes presentation changes through the project row, requires a draft and compares the saved source digest with the digest supplied by the API. On success it archives the former published row and promotes the draft. Retrying an already published row returns it without making another revision. Archiving clears that row’s published_by and published_at; those columns alone are not a complete retained publication-event history.

flowchart LR
S[Canonical project sources] -->|capture selected facts| D[Draft revision 3]
E[Staff editorial changes] --> D
P[Published revision 2] --> C[Admitted customer]
D -->|review and source check| N[Publish revision 3]
N --> A[Archive revision 2]
N --> V[Current published revision 3]
V --> C
Saving an internal revision leaves the earlier customer revision in place. Publication explicitly replaces it after review.

The saved snapshot records schema version, project identity/number/title, a hash of the current published project description, agreement total, ordered quote IDs and totals, and published file IDs. captured_at is added after hashing, so time alone does not make the same captured facts stale. Changes to these captured facts require a new saved/reviewed draft before publication.

This digest is deliberately a selected projection. It is not a checksum of every quote line, contact field, file byte, planning pass or accepted evidence record. The API builds the current payload before entering the publish RPC; the database compares the supplied digest, rather than recomputing every source inside that transaction. Consequently this mechanism does not certify a complete concurrent source freeze. Accepted-term immutability and each other record’s guards retain their own responsibilities.

The customer renderer overlays published editorial content onto the current safe customer payload. Current commercial summaries, permitted files, planning and messages are still loaded through their own owners. The presentation snapshot is not a frozen copy of the entire portal page. A withdrawn or cross-project media reference is omitted even when the saved presentation still names its file ID.

projects.description_md holds the last published description. New initial text is stored separately as a staff seed, not copied into that customer-readable column. Presentation publication applies description_md to the project in the same database transition and removes the seed. Omitting the key preserves legacy behaviour; explicit null publishes removal. Pre-existing published descriptions were retained when this boundary was introduced.

An office preview is a read-only composition of the customer projection. The editor can also hold unsaved text and a draft that the customer does not receive. Opening a preview, saving a draft or selecting a template does not publish it, send mail or accept an agreement. Follow the admitted customer’s actual read path to establish what is visible. If the presentation relation is unavailable, the read model explicitly reports migration state to staff and falls back to the existing customer projection; that fallback is not a successful publication.

For example, revision 2 says “Prepare and paint the hallway” and is published. Staff saves revision 3 with a revised introduction and next step. The customer still sees revision 2’s editorial text. If a captured source total or file-ID set changes before publication, the stored source digest no longer matches and publication is refused until staff saves and reviews the current source. Publishing revision 3 replaces the editorial text; it does not accept a revised price. A current planning release can change alongside revision 2 because planning is independently owned.

The current planning API uses publish_project_planning, not the older publish_project_schedule projection. Its command binds company, project, actor, expected planning revision and idempotency key/request hash. The transaction rejects a stale preview, invalid promise, unpublishable booking or a deviation without the required reason. It captures customer-facing titles/notes and dates from qualifying order passes, excluding absence and cancelled work.

A changed or previously withdrawn plan creates a new numbered snapshot and queues one version-specific planning notification. An identical current snapshot reuses its version. Publication and enqueueing do not prove email delivery or customer appointment acceptance. The confirmation action does not approve work or transfer worker time to payroll.

Withdrawal marks the latest publication withdrawn. Both the customer project payload and project list inspect the latest snapshot. If it is withdrawn, they return no published dates rather than falling back to an older plan. Internal bookings remain available for staff to revise. A later release creates a new version. Previously read or delivered information cannot be recalled by hiding a future portal projection.

Worker-order and schedule flags expose current instruction/pass rows through the worker projection. They do not preserve the same frozen history as customer planning. An order’s publication is separate from assignment, an assigned pass and approved time. Some worker actions are permitted by assignment even when a delivery flag is false; use the detailed access reference before treating a flag as a universal write gate.

Publishing a customer file checks verified content and the exact project’s Storage path. Retraction is allowed even for a bad previously published file. Worker publication creates or reactivates an approved exact-order link; revoking that link does not delete the file. Signed links expire, but visibility withdrawal is not immediate revocation of already-issued links or saved copies.

A conversation attachment is shared through its conversation. Staff must separately choose customer project-image visibility before a presentation can resolve it as media. Changing a presentation does not edit earlier messages, erase attachments or move an internal conversation into the customer audience. Audience membership, resource scope and content publication must each be checked where that read occurs.

The delivery PR identifies executed checks and candidate revisions. Synthetic presentation tests cover bounded content, readiness blockers, stable captured hashes, safe media resolution and overlay behaviour. Customer-route tests cover the planning read projection and agreement boundary; database tests separately exercise the current expected-version overload and planning lifecycle. Their fixtures and executed results must be read at the named revision.

No claim here certifies every concurrent source mutation, a complete immutable publication-event log, immediate signed-URL revocation or independent Vi Målar business acceptance. Those limits are not removed by a documentation review.