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.
Publication owners and reader checks
Section titled “Publication owners and reader checks”| 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.
Customer presentation revisions
Section titled “Customer presentation revisions”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
What the source digest checks
Section titled “What the source digest checks”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.
Description, preview and published output
Section titled “Description, preview and published output”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.
Planning confirmation and withdrawal
Section titled “Planning confirmation and withdrawal”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.
Files, work and conversations
Section titled “Files, work and conversations”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.
Verification scope
Section titled “Verification scope”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.